Aminet 3/Aminet 3 - July 1994.iso/Aminet/text/show/xMore14.lha/xMore.doc

Text File | 1994-04-11 | 24KB | 682 lines

                                 xMore 1.4
                               10 April 1994

      Copyright (c) 1993,1994 by Jorma Oksanen. All rights reserved.

xMore is a freely distributable, copyrighted piece of software.

Since xMore is free, it comes with NO WARRANTIES.  The author is not
responsible for any loss or damage arising from the use or inability to use
xMore; the user takes all such responsibility.

No charge may be made for xMore, other than a nominal copy fee.  xMore may
not be distributed with a commercial product without the author's prior
consent.  xMore must be distributed with all documentation intact and
unaltered.  Permission is expressly granted to Fred Fish to distribute on
his fine collection of disks.

Although xMore is freeware, DONATIONS WOULD BE GLADLY ACCEPTED, either
money or stuff you've written yourself.


What is it?
-----------

Yet another file reader, you might think, and you are right.  I missed
small XPK-understanding file reader with reasonable feature list, but there
was none available.  Most ( (c) 1992 by Uwe Röhm) can hardly be called
small (but it surely has 'reasonable' feature list!).  I have to admit that
xMore is currently bigger than I planned it to be, but people don't seem to
want small programs, they want features!  So, what do you get?

    + light speed search! No loss of speed even if case insensitive
      and/or backwards!
    + wildcard search. Searching doesn't slow down if only "?" is
      used (in fact it is FASTER when "?" is used).
    + hex mode.
    + FAST scrolling. Should beat Most (pun intended) textreaders
      using customized Text() function with custom screen.
    + displays ANSI styles (no colors) and some backspace-styles
    + variable TAB size! (now you can read those funny #?.c
      files with too much TABs ;)
    + can start one of the four possible editors.
    + freely definable keys!
    + font sensitivity, user definable font.
    + definable window dimensions, defaults to display size.
    + opens on any public screen or opens it's own screen.
    + multiple files from shell, Workbench and file requester.
    + pipe support.
    + clipboard support.
    + Support for Directory Opus compatibility.
    + character conversion.
    + lots of small details like default zoomed size exactly one
      line high. Small things make the difference!
    + can be made resident (has been pure from day one, but who
      remembers to mention everything)
    + OS 2.04 required (sorry, v36 users. There just is too much
      functions in RKMs with text 'this function is broken in V36'
      that I didn't bother dodging them. To pre-2.0 users xMore is
      Yet Another Reason To Update. Come on guys, do you use CP/M
      at work or what ? ;)
    + Can read files containig more than 65535 lines! With hex mode
      this is MUST (256K+ file in narrow window = lots of lines!).
      (This would be suitable place to mention certain well-known
      directory utility and another XPK-supporting reader which both
      assume no-one has REALLY big files, but that could give offence
      to JP and UR, so I won't)

    - wildcard search only supports "?"
    - reads whole file into memory (EVERYBODY has min. 1 Meg today)


Installation
------------

Just copy it!  If you want to get Most of it, check that you have in your
LIBS:  drawer the following libraries:

  asl.library        needed for file requester
  commodities.library    needed for defining keys (more about that later)
  diskfont.library    needed if you use disk-based font
  iffparse.library    needed for clipboard cut/copy/paste
  xpkmaster.library    reason for xMore's existence!

You also need clipboard.device in DEVS:  if you intend to use clipboard
(makes sense or what ?).

xMore works just fine (althought slightly limited) without any disk-based
libraries, so it's easy to use with floppy systems and distribution disks.


Usage
-----

  From workbench:

    Just double-click on xMore's icon and it will open the file requester.
    Alternatively you can select one or more text files with extended
    selection (RTM) and then double-click on xMore.  And ofcourse it works
    fine as default tool, too.

    If you give a drawer to xMore as one of the arguments, xMore will open
    file requester in that drawer.



  From shell:

    Type "xMore" followed with zero or more file names.  xMore acts just as
    it would from Workbench:  without arguments it opens file requester, if
    you give it a directory name, file requester opens there.  It makes no
    sense to give more than one drawer to xMore.


  You can use multiple selection from file requester too.  xMore does not
  close it's window until you quit the last file you gave to it, but you
  can force it to quit without reading rest of files using control-esq (or
  whatever key you have binded FORCEQUIT to).


Options
-------

Abbreviations for options (only from shell) are in parenthesis.
xMore silently discards lines it can't parse in settings file.

¹ FILES
    Specify files to read (what else?)

² DEFAULTDIR
    Specifies directory where xMore opens it's initial filerequester.

³ SETTINGS
    Specifies settings file to read. Default is "ENV:xMore/xMore".

³ NOSETTINGS
    Inhibits settings file reading.  From shell, also inhibits tooltype
    parsing.

  PUBSCREEN (S)
    Name of public screen where xMore opens its windows.  xMore will open
    screen if it isn't already open.  This screen will be closed when xMore
    quits.  If you have open windows on xMore's screen you will get
    requester telling you to close all windows to allow xMore to quit.

  SCREENMODE (SM)
    Screenmode used to open new public screen.  If mode is not specified,
    xMore tries to open screen with same screen mode that Workbench uses.

  FONT (F)
    Name of the font used.  Given with format <fontname>/<fontsize>, where
    fontname may contain path.  xMore does not accept proportional fonts,
    fonts higher than 64 points or fonts that are written from right to
    left (sorry about that last one ;).  If font is not given or it's not
    within above limits, system default font will be used.
    If you have 68020 or better and the font is 8*8 pixel font, xMore uses
    it's own Text() routine whenever possible.  On bog standard
    A1200/030/50MHz with 10Mb Fast memory this means 200000 chars/second
    raw rendering speed.

  WINDOW (W)
    Position and dimensions of window.  Given as left/top/width/height.  If
    you omit any of the parameters, default will be used.  Note that
    intuition may move and/or shrink the window to make it fit to screen.

  UNIT
    Clipboard unit to use. Default is 0.

  RMBQUIT
    If this switch is given xMore will do FORCEQUIT when right mouse button
    is pressed below title bar.  To access menus you have to position the
    pointer at (or above) title bar.

¹ TEXT/ASCII & HEX
    Force filetype to text or hex.  If filetype is not given, xMore will
    determine type by first bytes of file.

² FILETYPE
    Tooltype/setting equivalent of above. Can be TEXT/ASCII or HEX.

  TABSIZE (TAB)
    Sets TAB size.  Default is 8. Maximum is 32.

  SPACING (SPC)
    Number of extra pixels to insert between lines. Default is 0. Maximum
    is 32.

  FASTSCROLL
    Specifies how many lines SCROLLUP/SCROLLDOWN will scroll at once. This
    can be used to speed up scrolling of large windows. Lines scrolled at
    once is calculated as MIN(1,(visible_lines-1)*FASTSCROLL/100), so
    FASTSCROLL 0 scrolls one line at time, while FASTSCROLL 100 forces
    SCROLLUP/SCROLLDOWN to act like PAGEUP/PAGEDOWN. Default is 0.

  CONVERT
    Specifies conversion file to read. Default is "ENV:xMore/convert".

  NOCONVERT
    Inhibits conversion file reading.

² EDITOR/XEDITOR/XPKEDITOR/XPKXEDITOR

    Specifies program to run when you try to run editor. If window is in
    hex mode, XEDITOR is started insted of EDITOR.  If current file is
    compressed, XPKEDITOR or XPKXEDITOR is used instead, allowing you to
    have different editors for packed and non-packed files.

    If needed editor is not specified in icon tooltypes or settings file,
    one of ENV:Editor, ENV:XEditor, ENV:xMore/Editor or ENV:xMore/XEditor
    is tried instead.

    Note that you can't start editor if the data came from clipboard or
    pipe. In that case you still can cut file to clipboard and paste it
    into your editor.

¹) shell only
²) icon tooltype/settings file only
³) not from settings file


Menus
-----

Menus look little pathetic at present as there are no keyboard shortcuts
for them.  I left them out so they wouldn't override your keyboard
definitions.  I will add ability to define shortcuts if you really want it.
Note that if xMore can't open gadtools.library, you won't get menus (but
xMore will otherwise normally).

  Project

    Open        Load new file(s)

    About        In addition to normal version/author text this one
            tells some file statistics too (just because that
            way you might see my name more often ;^D)

    Quit        Quit current file.  If you keep control down when
            selecting this item, forces full quit.

  Edit

    Edit        Start editor and quit

    Cut            Copy contents of current file to clipboard and quit

    Copy        Copy contents of current file to clipboard

    Paste        Read contents of clipboard


  Search

    Search for...    Asks for search string. Currently the search is
            always case insensitive if selected from menu

    Search next        Find next occurence of search string

    Search previous    Find previous occurence of search string


  Move

    Goto line...    Ask line number and move there

    Scroll up        Scroll up one page
    Scroll down        Scroll down one page

    Page up        Move one page up
    Page down        Move one page down

    Beg of file        Move to beginning of file
    End of file        Move to end of file

  BookMarks

    Mark location n    Set bookmark n to current line

    Jump to mark n    Move to bookmark n

  Misc

    TAB size...        Asks tabulator size

    File type
      ASCII        Displays file in ASCII
      HEX        Displays file in HEX


Keyboard
--------

To define keys yourself create file "ENV:xMore/keys" (don't forget to copy
it to "ENVARC:xMore/keys" !) which is read by xMore every time it's
started.  Each line describes one action and one key:  <ACTION>=<key>.
Note that equal sign ("=") must follow <action> without any blanks.  The
case of the characters IS significant.  Lines starting with ";" are ignored
just for those who need comment everything.

JUST TO MENTION:  YOU CAN DEFINE MULTIPLE KEYS TO SINGLE ACTION!  Somehow I
forgot to mention that in 1.2 docs.

JUST TO MENTION 2: (don't we all love sequels ?) People claimed that defined
keys didn't repeat. How about giving qualifier "-repeat" to key? Naa, too
hard. All MOVEMENT commands (UP - SCROLLDOWN) repeat by default, you can use
the "-repeat" to turn it off. All other actions act like C= intended them to
work.

JUST TO MENTION 3: For some weird reason "numericpad 9" doesn't work under
2.0. It works fine with 3.0... I'll check it someday...

Following is list of all defined actions with their default key bindings
and keywords.  If default key is missing, that just means that you need to
define it yourself if you want it.

Action            Default            Keyword

Up one line        up            UP
Down one line        down            DOWN
Left TAB chars        left            LEFT
Right TAB chars        right            RIGHT

Up one page        shift up        PAGEUP
Down one page        shift down        PAGEDOWN
Beginning of line    shift/alt/control left    STARTOFLINE

Beginning of file    control up        TOP
End of file        control down        BOTTOM

Scroll up one page    backspace        SCROLLUP
Scroll down one page    space            SCROLLDOWN

Search case insensitive    s            SEARCH
Search case sensitive    shift s            SEARCHCASE
Search next        n            NEXT
Search previous        p            PREVIOUS

Goto bookmark        F1 .. F10        * currently not definable
Set bookmark        shift F1 .. shift F10    * by user

Goto line        g            GOTOLINE
Set TAB size        tab            SETTAB
Set mode to ASCII                ASCIIMODE
Set mode to HEX                    HEXMODE
Hex/ASCII toggle    h            TOGGLEMODE
Full redraw        r            REDRAW

Cut    (copy to clipboard and exit)        CUT
Copy    (copy to clipboard)            COPY
Paste    (read from clipboard)            PASTE

Load new file(s)    l            LOAD
Edit current file    shift e            EDIT
Quit/Next file        ESC            QUIT
Force quit        control ESC        FORCEQUIT

Information requester    ?            ABOUT

Do nothing                    NOP

If you define two (or more!) actions to same key, the later will be used.
This allows you to override default keys.  NOP is useful if you want to
cancel default key without giving it new action.


Mouse
-----

You can scroll with mouse by pressing the left button in the upper or lower
part of the window.  Currently you can't scroll horizontally with mouse.


Hex mode
--------

When in hex mode, title bar shows file size (in hex, of course ;) instead
of number of lines.  xMore tries to preserve file position when changing
mode and when resizing window in hex mode.  This however is not as easy as
it sounds, so expect it to move slightly towards the beginning of file.


Piping data
-----------

To make xMore read data from pipe, give "*" as filename.  Pipe detection is
not automatic because of problems arising if you run xMore in background.
(Try "run Most" to see what I mean. If I just could find AmigaDOG manual
here in Finland...)

Current implementation reads data from pipe until end of data is reached
and then copies it to continuous memoryblock.  This means that xMore needs
twice as much memory than there is data in pipe.  On the other hand, this
implementation doesn't restrict scrolling any way.

You can't read XPK-packed files thru pipe (or you can, but they won't get
decompressed ;) as I don't see any reason for that.

You can mix "*" with regular filenames:

    xMore DOC:xMore *

will first read DOC:xMore and after that pipe contents will be read.

If your shell expands wildcards then you must give "*" with quotes.

If you specify "*" more than once in file list, you will likely get error
"Pipe is empty" for all "*"'s after the first.  So why would you want to do
that?

If your shell doesn't support pipes then check out <>< 673.  There is handy
command, PIPE, by Andy Finkel.  (This plug totally free!)

You can "run" the last part of pipe (ie.  xMore) but you can't "runback"
it.  `dir dh0: all | run xMore "*"' works, `dir dh0: all | runback xMore
"*"' doesn't.


Clipboard support
-----------------

To read data from clipboard use filename "-c".  If you want to specify unit
other than specified with UNIT keyword, append it's number to filename.
"-c3" will read data from unit 3.  You can use this from commandline and
file requester alike (I hope you don't have files named -c0 .. -c255).

You will get error "Clip is empty" if the data in clipboard is not IFF-FTXT
(also if clipboard IS empty, but that should be pretty obvious).

In low memory situations clipboard paste, like pipe reading, reads as much
as it can and displays truncated file.  Currently there is no warning about
this.


About ANSI (and other control codes)
------------------------------------

xMore 1.4 supports most of style setting codes, but not color.  This allows
faster scrolling, and I personally like xMore for it's speed.

xMore understands following ANSI codes:

<ESC>[0m    plain text
<ESC>[1m    boldface on        <ESC>[22m    boldface off
<ESC>[3m    italics on        <ESC>[23m    italics off
<ESC>[4m    underline on        <ESC>[24m    underline off
<ESC>[7m    reverse on        <ESC>[27m    reverse off

Of course you can mix styles:  <ESC>[1;4;23m will give bold, underlined
text.  xMore also understands <CSI> (0x9B) in place of <ESC>[ (0x1B,0x5B).

Other control codes

xMore handles backspace, tab, linefeed, formfeed, carriage return and esc
as special characters.  Form feed and carriage returns will be replaced
with "L" and "M" respectively.  Tab works like it should.  ESC-c (reset)
only resets styles.

As suggested by Ron Charlton, xMore also handles some special cases:

    character-backspace-character bolding
    underscore-backspace-character underlining
    character-backspace-underscore underlining

I remeber seeing these used in some UN*X .man files, so they might be
useful to others than Ron too...


Character conversion
--------------------

xMore can automagically convert accented characters from ANY machine as
long as there is equivalent character in Amiga.  In addition to standard
(not so standard with text readers ;) one-to-one conversion xMore can
convert multiple characters to zero or more characters.  By default xMore
reads the conversion rules from file "ENV:xMore/Convert" but you can
specify other file with CONVERT argument.

Conversion file format is extremely simple:  first, ascii codes to convert,
followed by ascii codes to convert to.  If giving multiple codes, just
separate them with single comma.

 13,10    10        CR,LF to LF    bye bye M
 26            EOF to nothing

 58,41    40,58        turns :) to (:

 65,112,112,108,101    65,109,105,103,197    Apple -> Amiga ;)

xMore stops parsing line when it hits first character that isn't number or
whitespace, so you can freely add your comments as long as they don't start
with number.


Limitations and all this depressing stuff
-----------------------------------------

xMore resets style for each line, so some styles may be lost.  Even those
text readers using console.device have some problems with ANSI continuity,
so I won't be fixing this (at least not today).

Backspace can only back over on style change, so
    "text"<bold on>"."<bold off>"."<6 backspace>"text"
displays "texttext" instead of "text".

Backspaces starting after displayable width won't be parsed, even if they
would cause more text to be visible.

When reading files with more than 65535 lines, clicking inside scrollers
container will likely move couple lines less than page height.  I *WON'T*
add floating point calculations to fix rounding bugs ;b

Horizontal scrolling may cause some weird things to happen to lines
containing ANSI codes/backspaces.  If you find some really annoying ones
then let me know.

There is a bug in xpkmaster.library 2.4 which returns error "Input file
truncated" if you try to read file shorter than four bytes.

Asl.library v37 does not allow opening requesters on other screen than
default if there is no window on that screen, so initial filerequester
opens on default public screen.  WB 2.1 and later open all requesters on
xMore's own screen (if opened, of course ;).

Pre-v39 iffparse.library has some bugs in it, which may result in
unpredictable behaviour.  They however should not happen until you try to
cut/copy/paste with really low memory.

xMore already had ARexx interface but I had to remove it to hurry the
release of this version.  Keep on waiting (but don't hold your breath).

Documentation propably lacks lots of information, but nobody reads docs
anyway, so it ain't so bad...


Acknowledgments
---------------

To keep men-in-suits away from my door, here is list of products mentioned
in this document and their trademark holders.  If you think that I've
forgotten some, inform me before sending your men after me and I'll happily
revise this list.  (Happily?  Yeah...)

"Directory Opus" is trademark of InovaTronics, Inc.
"Amiga" and "Workbench" are registered trademarks of Commodore Amiga, Inc.
"ARexx" is a trademark of William S. Hawes.


Thanks
------

To all of my beta testers (there are lots of them - I consider 1.0 as beta
version of 1.1!).

To Urban Dominic Mueller, Bryan Ford and all others who make XPK feel
better than sliced bread.

All who have sent bug reports and suggestions for new features.  Keep the
flames on!

And last but not least to Tommi Lahtonen for being my link to the net.


History
-------

; 1.0    ????
;
;    First public release
;
; 1.1    15.10.1993
;
;    If file was considered non-ASCII hex flag was toggled, not set.
;    All errors given in requester if started from WB or run in
;    background shell.
;    Opens filerequester in specified directory (from WB too!).
;    Filerequester defaults to previous files directory.
;    Filename in window title no longer shows path.
;    If given file is not found, and name does not end with
;    ".xpk" or ".pp", xMore tries these exensions before reporting
;    error. This is true only from workbench arguments.
;    Search works in hex mode (it worked before, but position to jump
;    to was calculated in ASCII-lines).
;    Bookmarks now refer to line start address instead of line number
;    to fix above mentioned hex-mode problem.
;    Cursor left with ANY qualifier moves to extreme left
;
; 1.2     9.12.1993
;    Attempting to prevent Great Keymapping Wars xMore now features
;    arbitrary keymapping if commodities.library is available.
;    Only ROM-based libraries are absolutely necessary.
;    Lots of internal restructuring. Source looks much nicer now ;)
;    At last distributed with something that can be called documentation
;    (not perfect yet; coding is much easier than writing docs!).
;
; 1.3    07.01.94
;    Menus.
;    ANSI styles! Backspace bolding/underlining.
;    Added tooltype parsing. DEFAULTDIR from Workbench.
;    User definable PUBSCREEN, SCREENMODE, FONT, WINDOW, ASCII, HEX
;    and TABSIZE.
;    Can start editor from xMore.
;    xMore used to quit if file requester was canceled.  Nobody complained
;    about it, thought.  It annoyed me, it's gone.
;    xMore no more gets confuzed about NEWSIZE when input gadget active.
;    Default window is now adjusted so that you can reach screen front/
;    back gadget.
;    Line number refresh is fixed for 3.0 (many readers suffer the very
;    same phenomena.  Too smart OS?).
;    You can't define keys to other events than rawkey anymore.  Naturally
;    they didn't work before as they were parsed as keybord input.
;    Scroller gadget looks nicer now.
;    Some hex mode rewriting - no sideways scrolling, preserves position
;    when changing mode.
;    Tabs code was totally broken. I wonder how it could work at all.
;    Added information requester.
;    Added clipping to prevent border-trashing.
;    Removed 16-bit calculations -> can read BIG files.
;
; 1.4    10.04.94
;    Now recognizes window size changes correctly.
;    Pipe and clipboard support added.
;    Supports reverse character/cell colors. Form feed/carriage return
;    displayed as reverse "L"/"M".
;    Can backspace over one style change, speeds up backspace-styles a lot!
;    Scrolling with left mouse button. Forcequit with right mouse button if
;    RMBQUIT given. This one for DOpus freaks.
;    Menu multi-selection works.
;    Mysterious Software Failure found - I forgot to RemoveGadget() the
;    scroller, leading to wild reads after DisposeObject(). What's worse,
;    CloseWindow() tried to free gadget memory - kaboom 8(
;    Argument parsing rewritten. Now reads arguments from commandline (if
;    started from shell), then fills in non-specified arguments using icon
;    tooltypes and finally from settings file.
;    Interline spacing.
;    Uses custom Text() routine if machine and font permit it (68020+, 8*8
;    font). Disabled on V39 machines if RastPort doesn't support per-plane
;    masking (display boards).
;    Uses project-specific FILEMODE and TABSIZE tooltypes.
;    If you changed tabsize while having scrolled right, titlebar still
;    displayed horizontal offset.
;    Fixed lockup when trying to jump to unset bookmark (yet another
;    "optimization" 8(
;    Tab code changed, hopefully last time.
;    Automagic character conversion.
;    If xMore doesn't have path, copies it from Workbench. Should help
;    when starting editor with activator (CEd, GoldEd ...).
;    If xMore has to determine the screenmode, it takes it from default
;    public screen instead of Workbench.


Future
------

Up/down paragraph with alt up/down.  Show percentage.  Goto percentage.
Word wrap.  App icon/window.  Help!  Multi-window mode.  Full wildcard
search.  Highlight text found during search.  Mark data to cut/copy to
clipboard.  Smooth scroll.  Ability to read crypted files.  Ralliraidat.
etc.

And maybe some bug fixes...  Come on guys (and gals!), send me bug reports.
I know of several minor bugs which I won't bother to fix before someone
else mentions them.


Contacting the author
---------------------

I can be reached with comments, suggestions, bug reports, praise, money
etc.  at the following address:

    Jorma Oksanen
    Ratastie 5 A 3
    14200 TURENKI
    FINLAND

or by e-mail: [e-mail]

If you send bug report(s), remember to mention version of xMore and
kickstart you are using.